micro agent
一个使用ts实现的微小而强大的 agent ，可以移植到任何地方进行使用
主要应用场景：嵌入各个网站，让原有网站在简单改造后即可拥有ai对话以及 agent 自动化操作能力，例如表单填写，数据筛选提取。网站只需声明一些tools，以及配置一些提示词。
agent 是利用大模型来实现动态编码程序的一种形式。
动态编码则是减少人工开发时间，同时得到运行速度快的方案
大模型的注意力机制就决定了你输入的约束条件越多，它遗忘和丢失关键信息的概率就越大。
如果你不够聪明的话，折腾来折腾去，你得很久以后才会发现，纯净上下文的 model 比任何狗屁方法论都好用，model 的基础能力才是一切。
Agent 架构说明
整体架构
这是一个 Tool-Use Agent（工具调用型 Agent），运行在 WPS 加载项的 webview 中。核心设计思想是：让 LLM 通过唯一的 bash 工具在虚拟终端中执行 CLI 命令，间接操作 WPS 文档。
┌─────────────────────────────────────────────────┐
│ index.vue (UI 层) │
│ - 用户输入、日志展示、暂停/停止/撤回控制 │
│ - LLM 提供商选择、SSE 流式解析 │
│ - 文档选区自动轮询 │
└──────────────┬──────────────────────────────────┘
│ runAgentLoop(config, signal)
▼
┌─────────────────────────────────────────────────┐
│ agentLoop.ts (主循环) │
│ - LLM ↔ Tool 循环 (最多 80 轮) │
│ - 上下文压缩 (compactMessages) │
│ - 连续失败反思、空响应重试 │
│ - Todo 未完成阻止退出 │
│ - 技能切换 (switch_skill) │
└──────────┬──────────────────┬───────────────────┘
│ │
▼ ▼
┌──────────────────┐ ┌──────────────────────────┐
│ agentCore.ts │ │ virtualBash.ts │
│ - 类型定义 │ │ - 命令行解析器 │
│ - token 估算 │ │ - 管道 | / 链式 && || │
│ - 上下文压缩 │ │ - 内置文本工具 │
│ - 错误分类 │ │ - 模糊匹配 & 弱模型回退 │
│ - SkillConfig │ │ - 变量展开 ($VAR, $?) │
└──────────┬───────┘ └──────────┬────────────────┘
│ │
▼ ▼
┌─────────────────────────────────────────────────┐
│ Skills (技能层) │
│ ┌──────────────┐ ┌──────────────────────────┐ │
│ │ paibanSkill │ │ writeSkill │ │
│ │ 公文排版 │ │ 公文写作 │ │
│ │ 11个CLI命令 │ │ 流式写入+writeDoc命令 │ │
│ └──────┬───────┘ └──────────┬───────────────┘ │
└─────────┼─────────────────────┼─────────────────┘
│ │
▼ ▼
┌─────────────────────────────────────────────────┐
│ cli/ (CLI 命令层, ~15 个命令) │
│ doc, fmt, batch, margin, font, para, head, │
│ search, find, split, selection, writeDoc, │
│ report, history, env, todo, help, switch_skill │
└──────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────┐
│ docOperationLayer.ts (文档操作抽象层) │
│ - 写前自动选中 + 滚动队列(去重) │
│ - 写前快照 + 写后验证 │
│ - 生命周期钩子 (beforeWrite/afterWrite/onError) │
└──────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────┐
│ wpsTools.ts (WPS API 封装) │
│ - 段落查看/排版/字体/格式/搜索/替换/删除/写入 │
│ - 格式预设 (国标公文格式) │
│ - Markdown 加粗语法处理 │
└──────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────┐
│ WPS Document API (window.Application) │
└─────────────────────────────────────────────────┘
核心设计模式
LLM 只暴露一个 bash function tool，所有能力通过虚拟终端命令实现。这是一种经典的 Agent 设计，好处是：
通过 SkillConfig 接口定义可插拔的技能模块，当前有两个技能：
paibanSkill — 公文排版（11 个 CLI 命令）
writeSkill — 公文写作（1 个 CLI 命令 + 流式写入）
Agent 启动时所有技能的命令都注册到 CLI 中，LLM 通过 switch_skill 命令切换，切换后注入对应的系统提示词。
参考了多篇 Agent 优化论文实现了一套渐进式压缩策略：
Tool Result Clearing（自适应轻量压缩）：保留最近 N 条完整、渐进压缩更早的、激进压缩最旧的
错误记录保护（P9-C/Manus）：错误记录保留更多行，防止模型"忘记教训"
轨迹去重（P10-B/AgentDiet）：合并连续重复的 tool 调用
结构化摘要：压缩时生成包含 session intent + 进度 + 操作脉络的摘要
在 CLI 命令和 WPS API 之间增加了中间层：
写前快照 + 写后验证（类似 Claude Code 的"先读再写"）
从文本中提取命令（处理弱模型不生成 tool call 的情况）
错误分类（deterministic/transient/capability）+ 修复建议
评估
优点
1.
架构清晰，分层合理 — 从 UI → 循环 → 虚拟终端 → CLI → 操作层 → WPS API，每一层职责明确，耦合度低
2.
上下文工程做得扎实 — 参考了多篇论文（Manus/AgentDiet/LangChain Deep Agents），渐进式压缩策略比简单截断效果好很多
3.
容错机制完善 — 模糊匹配、弱模型回退、错误分类、连续失败反思、空响应重试等多层容错
4.
Skill 系统可扩展 — 新技能只需实现 SkillConfig 接口即可接入，命令去重机制也考虑到了
5.
文档操作层设计好 — 写前快照 + 写后验证 + 滚动去重 + 生命周期钩子，既保证了正确性又兼顾了用户体验
可改进方向
1.
单工具瓶颈 — 所有命令走一个 bash 工具，LLM 需要自己拼命令字符串，容易出现格式错误。对于核心操作（doc/fmt/batch/writeDoc）可以考虑暴露为独立 tool，减少命令构造失败
2.
错误恢复未充分利用 — classifyError 定义了很好的三层错误分类（deterministic/transient/capability），但 agentLoop.ts 中只用了 consecutiveFailures 计数，没有根据 ErrorCategory 做差异化处理（比如 deterministic 直接给修复建议而不计入失败）
3.
writeSkill 的流式写入状态管理脆弱 — lastStreamLen 用增量截取处理累积文本，如果 LLM 流式中途改变前文（虽然少见），会导致内容不一致
4.
缺少并行 tool\_call 支持 — 当前循环中 toolCalls 是顺序执行的（for (const tc of toolCalls)），而 LLM 可能一次返回多个 tool_calls，并行执行可以显著提升效率（比如 margin && doc 可以并行）
5.
LLM 调用层和 UI 层耦合 — createLlmCaller 在 index.vue 中定义，包含了 SSE 解析、联通 API 适配、重试逻辑等，职责较重。可以抽到独立的 llmService.ts
6.
缺少可观测性 — 没有结构化的性能指标采集（每轮 LLM 耗时、token 使用量、命令成功率等），对后续优化缺少数据支撑
7.
测试覆盖 — 存在测试文件（agentCore/agentBenchmark/agentIntegration），但核心的 agentLoop 和 wpsTools 因依赖 WPS API 难以测试，docOperationLayer 的 mock 策略值得进一步完善
总体评价
这是一个工程质量较高的 Tool-Use Agent 实现，特别是上下文压缩和文档操作抽象层的设计展现了较深的思考。架构上借鉴了 Claude Code 等成熟产品的设计理念（虚拟终端、先读再写、结构化日志），并结合 WPS 文档操作场景做了合理的适配。当前最适合的场景是公文排版和写作这类操作步骤明确、命令可枚举的任务。如果要扩展到更复杂的文档处理场景，建议优先解决并行 tool_call 和独立 tool 暴露的问题。